Ironwrapper Settings

This chapter is a rather complex one, we will introduce many Ironwrapper low-level features, some of them might not be easily understood without technical background.

General (Menu Item => Ironwrapper => General)

This UI defines general wrap settings:

Crash Dump

All softwares have errors and bugs not detected and fixed before product release. To the customers it is really a bad experience to see your application dies mysteriously or ugly (popping error message box from Windows operating system). To fix a random runtime issue without any debug data is almost impossible for software developers, that's why Microsoft has developed system facility to gather crash information.

Many years ago on Windows 3.x, Win9x, Windows 2000 and Windows XP, Microsoft uses \emph{Dr. Watson} to create crash information dump for crashing applications, and it is enabled by default. Since Windows Vista, however, Microsoft replace s DrWatson with a new error report engine WER: Windows Error Report, and to enable crash dump for an application, you must manually edit registry as administrator, which is usually hard for non-technical customers.

Ironwrapper has implemented a feature that generates crash dump automatically when the SoftwareShield protected application is actually crashing, and it does not need to change registry. It is based on \emph{WER} API so the crash dump file is in a standard format that can be parsed and loaded by Microsoft Visual Studio IDE or WinDBG. The crash dump file created by wrapped application also contains extensible information from Ironwrapper kernel, so that given a crash dump, we can parse it with a special tool to have a detailed memory layout information, which is very helpful to figure out the root cause of the crashing issue.

When the wrapped application is crashing, a crash dump of specified type is generated and a message box will pop up:

The crash dump file is named after the pattern: ProductName.ProcessID.dmp

Crash Dump Folder

Crash dump folder specify where the crash dump file will be saved, it is a full path name and supports environment variables, the default path is %USERPROFILE%\gs5\crashdumps.

• If Crash Dump folder is not specified (or blank), the default path is: %LOCALAPPDATA%\CrashDumps\;

• You can use any environment variables as part of the folder name;

• We have a built-in macro MountPoint, it is the full path to the install directory of your application. If your application is installed in a folder with write permission, set the path to %MountPoint%\CrashDumps\ so that the crash dump file will be saved in the sub-folder of install directory.

Crash Dump Type

There are 4 types of crash dump:

1. Min: The crash dump contains only basic set of data: system information, process information, module information, thread information, thread stacks, instruction window (256 bytes of memory around the current instruction pointer), and exception information.

2. Small: It includes basic data set and other memory data area pointed to by pointers in every thread stack memory. The referenced modules in the process memory space are also saved.

3. Large: The crash dump contains all read and write memory data, data segments of main application module, handles, threads.

4. Huge: All memory data, all modules, full thread details are saved;

Single Application Instance

When this option is turned on, only one instance of wrapped application can run at the same time,

IO Protection

These options disable system Open File dialog, Save As File dialog, Print dialog.

When you are wrapping a private document (PDF, DOC, etc.) these options can be useful to prohibit illegal copy and print.

Qt Wrap Options

How the Qt files are shipped with output application.

• Embedded in First Package: All Qt files are wrapped into the first application package, resulting in a single and bigger exe. It takes extra time to wrap all Qt files to the main package.

• Embedded in Separate Package The Qt files are deployed as a standalone package. Actually the SoftwareShield IDE has a pre-wrapped Qt package so the building speed is as quick as a plain file copy.

• Don't Embed Qt: Qt files are simply copied to output directory.

Optimization

Optimization settings for Ironwrapper.

• Not Optimized: Ironwrapper will not optimize the input settings. it just uses settings in IDE to process wrapped files.

• Optimzied for Maximum Speed: Ironwrapper should optimzie the wrapping for maximum execution speed. When wrapping, Ironwrapper will use compressor with maximum decompress speed, encryptor with maximum decrypting speed, the settings for individual files are ignored.

• Optimized for Minimum Size: Ironwrapper will use compressor with maximum compress efficiency, reuse the same compressor and encryptor module for all file processing in order to get a minimum output file size.

Packages

SoftwareShield can wrap app binaries into one of multiple packages, each package serves as an encrypted container to embed all kinds of app files such as executable files (*.exe, *.dll, .ocx, etc.) , plain document files (.pdf, *.txt, etc.), app data and media (audio and video, flash, etc.) files.

You can also think of the package as a portable data file that contains a hierarchical virtual file system that can be mounted to the SoftwareShield kernel at runtime, by embedding a subset of app files into a package, it can only be mounted and accessed by licensed users. For huge games with many sub-modules or game extensions, the package can help you deploy and license your product in an secure, incremental and controlled way.

Create a new package

By default the SoftwareShield IDE creates a package for each new license project, you can add more packages by pressing New button, the following video shows how to create a new package called "My Data.dat":

Delete a package

To delete a package, first select the package to delete in the package listbox, then press the "Delete" button.

Edit a package

• Package Name

  The output file name of the package.

  Basically package has no naming convention, it can use any file name as needed; however, the package's name is also related to its Head Path which we will explain later.

• Package ID

  It is an unique string identitifier associated with the package, SoftwareShield IDE generates a UUID for each package and you can leave it untouched in most cases.

• Head Path

  Head Path specify which app executable (*.exe, *.dll, *.ocx) should be the bootstrapping one when the package is loaded. It is the most important parameter for a package.

  There are two kinds of package:

  1. Pure Data Package

  There is NO head path specified, hence the package file itself cannot be loaded as excutable. It is also be called Head-less Package.

  A pure data package acts simply as a container, even it has no head executable and cannot be an executable by itself, you can put both executables and non-executable data files into it.

  2. Executable Package

  An executable head path is specified for the package. An executable package is a standard Windows PE (Portable Executable) file that can be loaded by Windows API (CreateProcess, LoadLibrary, etc.), if the head path is of an *.exe file, usually the package will inherit most of the head's resources (Version information, Icon, Manifest, etc.).

  For an executable package, if it will be executed by double-clicking on its icon like a normal exe by end users, then its package name must have .exe entension, if the executable package is a dynamic library (.DLL), or the package is an exe, but will be loaded as child process by Windows API, then its package name can be anything.

  Usually the package name and the head path is equal, but in theory the package name does not have to be the same as its head path, the package name is what the physical file looks file in the file system, the head path, however, is the file name of its head in the virtual file system within the SoftwareShield kernel.

  Sometimes it will improve performance and avoid false positive report from Anti-Virus product if the executable package does not have an file extension (like *.exe, *dll, *.ocx), anti-virus product usually tries to scan every suspect executables when app launching, it will take much longer time to scan a several hundreds MB exe file (remember our package file can be an executable file with thousands file embedded), so if possible, you can create a second pure data package to wrap most app files, leaving the main (usually the first) executable package as small as possible is a good idea for most cases.
  

• Command Line

  The built-in parameters as extra input to the package.

  For example, you are wrapping a game with optional start-up parameter, you can put the parameter as package's command line so that when the package exe is double-clicked, the pre-defined start-up parameter is automatically passed to the game exe.

  Another good example is, if you are wrapping a complete Java application as a normal Windows desktop exe, the command line is where you should specify all of the application's parameters (class path, main class, etc.) which are normally invoked as command line.

  Package's command line parameters specified in the IDE won't replace the actual command line parameters passed in by the operating system, they are extra ones prepended to the final command line the app's code will receive.

• Execute this package via Exe-Hopping

  Turn this option on if the head path of this executable package cannot be wrapped properly, which usually occurs when:

  1. The head exe is already protected by a third-party DRM solution;
  2. The head exe is generated from a non-standard development technology such as Flash, Director, Unity or Xojo, etc.
  3. The head exe has non-portable private data structure appended at the end of exe (data overlay);
  4. The head exe has a digital signaure;

  To protect this kind of exe, SoftwareShield uses Exe-Hopping technology to make sure the exe can access licensed packages properly.

Embedded Files

SoftwareShield Ironwrapper technology can wrap most kinds of app files and folders into several app packages. Once a file is wrapped, it is only visible inside the SoftwareShield virtual file system at runtime, so will not appear in the app installed directory and cannot be copied for illegal usage.

A wrapped file must be read-only by your app code, most likely the app used dynamic libraries (*.dll, *.ocx), media files (sound, video, image, etc.) are good candidates for wrapping. Any configuration file that will be updated by app at runtime, or any license / help file that should be visible to end users should not be wrapped.

The file wrapping GUI (menu: Ironwrapper => Embedded Files) is:

The left panel is a tree view of your app source, you can click the check box before a file to toggle the wrap settings.

• Wrap DLL File

When clicking on an executable file (*.dll, *.ocx, *.exe) there are two optional ways to wrap it:

1. Embed as Executable (Recommended): The dll file will be wrapped as an executable file. When wrapping as an executable, Ironwrapper will provide more dll-specific options on the right property panel.

2. Embed as Data: The dll file will be wrapped as a plain data file. When wrapped as a data file, it has all properties of a piece of data, it can also be loaded internally by Ironwrapper as DLL on demand.

• Wrap Data File

When a data file is embedded, it has some wrapping options:

• File Version: an integer version number for the embedded file; if the same file exists in another package but with a biggger version number, only the new file ( with bigger file version number) is accessible to the app. It allows you to upgrade app by shipping another package with changed files only.

• Virtualized File Name: The virtual file name inside the SoftwareShield virtual file system. Usually the physical file and virtual file shares the same file name and sub-folder, but it can be different if you want to map an app file to a new file name.

• Compression:

  1. Compressed: boolean, specify if the data file should be compressed internally;
  2. Compression Algorithm: if compression is enabled, specify how to compress the data file;

• Encryption:

  1. Encrypted: boolean, specify if the data file should be encrypted internally;
  2. Encryption Algorithm: If encrypted, specify how to encrypt the data file;
  3. Encryption Key: If encrypted, specify the per file encrypt key used for encryption;
  4. Is External Key: boolean, specify where to store the encryption key.

  • true: the key will be stored in the external license storage and will be injected to the app at runtime if and only if the file's associated entities or its container package is accessible ( the package's associated entity is unlocked or still in trial period ).

  • false: the key is stored inside the wrapped app package, it will be injected to the app at runtime when the package is loaded.

• File:

  1. Entity Names: Specify the file's associated entities. A file can only be accessed when any of its associated entities are accessible. If a file has no assoticated entity, it can always be accessed by default.

     You can select multiple entities for a embedded file:

     

  2. Embedded in Package: Specifies where to store the wrapped file. By default it is the first package, but if you have defined multiple packages, you can choose which package to store the wrapped file. It is useful that you create a pure data package to host all of your app data files and folders, it will make your executable package as small as possible, which might improve the app loading speed at runtime (ref: Optimize for Speed).

• Integrity Check: If enabled, SoftwareShield will check if the data file is not modified before accessing it.

• Misc:

  1. Public Access: boolean, specify if the embedded file can be accessed / visible to executables in other packages. If it is false, only executables inside the same app package can access the file, otherwise it can be accessed by all packages.

  Actually, the accessibility of a wrapped file is decided by two factors:

  File's Accessibility := (Package is Public) AND (File is Public)

If a packagte is defined as private, all its hosted files are private to other packages, if a packagte is public, its wrapped files defined as public can be accessed by other packages.

2. Chunk Size in KB: File is stored in small chunks inside package, you can specify the per file chunk size, by default it is "0", means the file is stored as a single chunk.

3. Visibility to Windows API: Specify the level of API visibility.

• Private (CreateFile Only): The file can only be accessed by CreateFile() api.

• Searchable ( Find/Search APIs): The file can be searched via FindFile / SearchFile apis.

• Visible to Shell Dialog: The file is visible in Open File Dialog GUI.

  It allows you fine-tune the file accessibility to Windows API, for example, if a file is wrapped in the "Private" level, then the file search apis cannot find it, as a result even the cracker injects a dll successfully into your process memory, it cannot create a copy of your file without knowing the exact internal file path.

4. Is INI file: Boolean, you must set it to true if the embedded file is in a real Windows INI file format. SoftwareShield will pre-process embedded ini file when wrapping so it can be accessed properly via Windows INI apis.

• Add / Remove Multiple Files with Regular Expression

  For app with hundreds and thousands of data files, SoftwareShield allow you add or remove them by specifying a file name pattern in either standard regular expression or DOS wildcard style.

  

  In the above example, we first set the name pattern to "playback10*", then press the "Remove" button, so that all pre-embedded files (playback101, playback102, ..., playback109) are de-selected.

Protect Not-Embedded File

Even a file is not embedded in a package, SoftwareShield can make sure its content won't be modified by checking its integrity before your app code is accessing it.

In the above example, the file "acknex.wdf" is not embedded, however, you can enable the Integrity Checking feature for this file so that if it is modified for some reason the app will fire warning event (EVENT_APP_INTEGRITY) to let the license model decide whether to quit the app accordingly.

Code Signing App in IDE

Code signing your app is very important if you want to provide best user experience:

• Your customer if confident that the app is from a trusted source and virus-free;
• Your app will not be marked as malware or trigger false positive alarm by anti-virus / security software;
• The web browsers won't block your app when downloading from web site;
• The Windows / MacOS won't bother your end users to confirm if the app can be launched.
• SoftwareShield Ironwrapper will detect if the code signaure is untouched when app launching, the wrapped app can only run when the app's code signaure is perfect so any illegal binary patching is not allowed.

When code sign feature is enabled, the SoftwareShield IDE will automatically code sign the wrapped binary as the last step.

You need three pieces of information for codesign:

1. Credential File (*.spc) It is also called "Software Publisher Certificate", the SPC contains the public key information and can be obtained from a third-party certificate authority (CA) that is authorized by Microsoft to issue such certificates.

2. Private Key File (*.pvk) It contains the private key information.

3. Password for the private key file

The code sign GUI in IDE is as following: ( Menu: Ironwrapper => Signing )

• Web URL: It can be anything unique, usually your app's web site.
• Description: A short introduction to your app
• Timestamp URL: Specifies the URL of the time stamp server. If this option is not present, then the signed file will not be time stamped. A warning is generated if time stamping fails.
• Credential File: The SPC file containing the public key;
• Private Key File: The PVK file containing the private key;
• Password: The password for the private key;

Press OK button, then the code sign information is stored in the license project file, next time when building project the IDE will code sign your wrapped app automatically.

Code Sign App in Command Line

Actually the process of code sign is based on Microsoft's SignTool toolkit, the necessary command line tools are shipped with IDE in the following folder: "IDE_Install_Dir\bin\Signing", you can manually code sign the app as following:

1. Create PFX file

  pvk2pfx /pvk pvkfilename.pvk [/pi pvkpassword] /spc spcfilename.ext [/pfx pfxfilename.pfx [/po pfxpassword] [/f]]

2. Sign App with SignTool

  signtool sign /f pfxfilename.pfx /p password /d "app description" /du "http://www.sample.com" /t "time URL" AppExe

You can automate the steps in your build script.